Skip to content

[docs] Obsolete PublishAsConnectionString migration guidance#1237

Open
aspire-repo-bot[bot] wants to merge 1 commit into
release/13.5from
docs/obsolete-publish-as-connection-string-263280fd9a435d00
Open

[docs] Obsolete PublishAsConnectionString migration guidance#1237
aspire-repo-bot[bot] wants to merge 1 commit into
release/13.5from
docs/obsolete-publish-as-connection-string-263280fd9a435d00

Conversation

@aspire-repo-bot

@aspire-repo-bot aspire-repo-bot Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#18044 — authored by @davidfowl.

Targeting release/13.5 based on the source PR milestone 13.5.

Why this PR is needed

PublishAsConnectionString (in both Aspire.Hosting and Aspire.Hosting.Azure) has been marked [Obsolete] in .NET Aspire 9.5 (microsoft/aspire#18044). The API only changes the manifest representation and does not affect other publishers, which misled callers. Existing users who call it will now receive a CS0618 compiler warning directing them to use AddConnectionString with execution context instead.

The docs previously contained code examples that called this API and a table entry listing it without any deprecation notice. Without documentation updates, users will see compiler warnings referencing an undocumented migration path.

Why docs are needed

Three signals fired from the source PR:

  • obsolete_attribute_added: [Obsolete] added to PublishAsConnectionString in AzureResourceExtensions.cs and ParameterResourceBuilderExtensions.cs
  • pr_body_has_deprecation_marker: PR body explicitly states the extension methods are being made obsolete
  • pr_label_breaking_change: PR carries the breaking-change label

Changes made

Updated: src/frontend/src/content/docs/fundamentals/external-parameters.mdx

  • Parameter example section: Replaced the .PublishAsConnectionString() call in the C# and TypeScript code examples with the preferred execution-context-based pattern using IsRunMode / executionContext.isRunMode. The run-mode branch adds the actual SQL Server resource; the publish-mode branch uses AddConnectionString.
  • Updated the accompanying numbered steps to reflect the new pattern.

Updated: src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx

  • Marked the PublishAsConnectionString row in the API naming-conventions table as (obsolete) and updated its description to point to AddConnectionString.
  • Added a :::caution callout block below the table explaining the deprecation and showing the correct ExecutionContext.IsPublishMode migration pattern.

Updated: src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx

  • Applied the same C# example update to the Japanese localized version (removed .PublishAsConnectionString(), used execution-context pattern).
  • Updated the Japanese steps list to match.

Files modified

  • src/frontend/src/content/docs/fundamentals/external-parameters.mdx (updated)
  • src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx (updated)
  • src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx (updated)

Generated by PR Documentation Check for issue #18044 · sonnet46 4M · ◷

@aspire-repo-bot
docs: document PublishAsConnectionString obsolete, update examples to…
155ee31 
… use AddConnectionString

- Update 'Parameter example' in external-parameters.mdx to use
  execution-context-based pattern (IsRunMode) instead of the now-obsolete
  PublishAsConnectionString() API
- Update the Japanese localized version of external-parameters.mdx to match
- Mark PublishAsConnectionString as obsolete in the azure/overview.mdx API
  table and add a migration caution callout showing the AddConnectionString
  pattern with execution context

Relates to microsoft/aspire#18044

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Jun 9, 2026
@aspire-repo-bot aspire-repo-bot Bot mentioned this pull request Jun 9, 2026
Merged
14 tasks
@aspire-repo-bot aspire-repo-bot Bot requested a review from JamesNK June 9, 2026 07:59
@aspire-repo-bot

aspire-repo-bot Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1237. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1237 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

@IEvangelist IEvangelist marked this pull request as ready for review June 26, 2026 15:13
@IEvangelist IEvangelist requested review from Copilot and davidfowl June 26, 2026 15:13
Copilot AI reviewed Jun 26, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates Aspire docs to reflect the deprecation of PublishAsConnectionString (Aspire 9.5) and guide users toward an execution-context-based pattern (AddConnectionString + run/publish branching).

Changes:

  • Updates external parameters examples to avoid PublishAsConnectionString and use execution context branching.
  • Marks PublishAsConnectionString as obsolete in Azure docs and adds a cautionary migration callout.
  • Updates the Japanese localized fundamentals page to match the new C# guidance.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File Description
src/frontend/src/content/docs/fundamentals/external-parameters.mdx Updates C#/TS examples and steps to remove PublishAsConnectionString and use execution-context branching.
src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx Marks API as obsolete and adds a caution callout with a migration example.
src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx Updates the Japanese C# example and steps to match the new execution-context pattern.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/frontend/src/content/docs/fundamentals/external-parameters.mdx
Comment on lines +645 to +649
// In run mode, add the actual SQL Server resource.
// In publish mode, use a connection string representing an external SQL Server instance.
const db = builder.executionContext.isRunMode
? await builder.addSqlServer('sql').then(sql => sql.addDatabase('db'))
: await builder.addConnectionString('db');
Comment thread src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx
Comment on lines +132 to +134
var resource = builder.ExecutionContext.IsPublishMode
? builder.AddAzureServiceBus("messaging")
: builder.AddConnectionString("messaging");
Comment thread src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx
Comment on lines +522 to 526
IResourceBuilder<IResourceWithConnectionString> db = builder.ExecutionContext.IsRunMode
? builder.AddSqlServer("sql").AddDatabase("db")
: builder.AddConnectionString("db");

var insertionRows = builder.AddParameter("insertionRows");
@IEvangelist

IEvangelist commented Jun 26, 2026

Copy link
Copy Markdown
Member

We've retriggered CI several times, and the current failures appear to be caused by changes in this PR rather than a transient runner issue. This likely needs updates in the PR content/code to get green checks.

@IEvangelist

IEvangelist commented Jun 26, 2026

Copy link
Copy Markdown
Member

[docs-from-code-ci] CI has been retriggered multiple times and is still failing. This appears to be due to the current PR changes rather than a transient infrastructure issue.

@IEvangelist

IEvangelist commented Jun 26, 2026

Copy link
Copy Markdown
Member

CI has been retriggered multiple times and is still failing for this PR (latest failures: 'CI' (attempt 7)). This likely needs changes in the PR itself rather than another rerun.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

CI has already been retriggered many times here, and the current failure still looks content-related rather than transient.

Latest failing signal: tests/unit/twoslash-blocks.vitest.test.ts reports 3 unexpected diagnostics from fundamentals/external-parameters.mdx (block #10). This PR likely needs a docs/sample fix before another rerun will pass reliably.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

This PR has had CI retriggered multiple times and is still failing on PR-specific checks. It likely needs a change in this PR to pass.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

[docs-from-code automation] repeated-rerun-note
CI has been retriggered multiple times and is still failing on this PR. This now looks likely to be caused by the PR changes rather than transient CI flakiness; it probably needs a content/code fix in this branch.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

We've retriggered CI many times on this PR and it's still failing. At this point, the failure likely comes from changes in this PR rather than transient CI flakiness, so this probably needs a content/code fix in the PR itself.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

CI has failed repeatedly on this docs-from-code PR after multiple reruns, and the failures appear to be related to the changes in this PR. Please review and adjust the PR content so the checks can pass.

@IEvangelist

IEvangelist commented Jun 27, 2026

Copy link
Copy Markdown
Member

CI has been retriggered multiple times on this PR and is still failing. The failures appear tied to the current PR changes rather than a transient runner issue, so this likely needs an update in the PR content before CI will pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@JamesNK JamesNK Awaiting requested review from JamesNK
@IEvangelist IEvangelist Awaiting requested review from IEvangelist IEvangelist is a code owner
@eerhardt eerhardt Awaiting requested review from eerhardt eerhardt is a code owner
@davidfowl davidfowl Awaiting requested review from davidfowl

Assignees

No one assigned

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@IEvangelist